In docs, explain what a dither offset is for.

1999-11-04  Havoc Pennington  <hp@pobox.com>

* src/gdk-pixbuf-render.c (gdk_pixbuf_render_to_drawable): In
docs, explain what a dither offset is for.
(gdk_pixbuf_render_to_drawable_alpha): Explain why you would use
this function vs. gdk_pixbuf_render_to_drawable().

diff --git a/gdk-pixbuf/ChangeLog b/gdk-pixbuf/ChangeLog
index 8df225dee6285733f1c82cd10bd4b486e588c20f..b53e541404abed694ca5a0f1c5fe522bad4b513f 100644 (file)
--- a/gdk-pixbuf/ChangeLog
+++ b/gdk-pixbuf/ChangeLog
@@ -1,3 +1,10 @@
+1999-11-04  Havoc Pennington  <hp@pobox.com>
+
+       * src/gdk-pixbuf-render.c (gdk_pixbuf_render_to_drawable): In
+       docs, explain what a dither offset is for.
+       (gdk_pixbuf_render_to_drawable_alpha): Explain why you would use 
+       this function vs. gdk_pixbuf_render_to_drawable().
+
 1999-11-04  Havoc Pennington  <hp@pobox.com>
 
        * configure.in: Use libart-config correctly; find gnome-config

diff --git a/gdk/gdkpixbuf-render.c b/gdk/gdkpixbuf-render.c
index a12e8ae66a9b89c463c826a7ce46e66c9d3f606b..147403c365461bde3c660a576025bb52726c3fd4 100644 (file)
--- a/gdk/gdkpixbuf-render.c
+++ b/gdk/gdkpixbuf-render.c
@@ -43,6 +43,7 @@
  * Takes the opacity values in a rectangular portion of a pixbuf and thresholds
  * them to produce a bi-level alpha mask that can be used as a clipping mask for
  * a drawable.
+ *
  **/
 void
 gdk_pixbuf_render_threshold_alpha (GdkPixbuf *pixbuf, GdkBitmap *bitmap,
@@ -174,6 +175,11 @@ remove_alpha (ArtPixBuf *apb, int x, int y, int width, int height, int *rowstrid
  * the GdkRGB visual and colormap.  Note that this function will ignore the
  * opacity information for images with an alpha channel; the GC must already
  * have the clipping mask set if you want transparent regions to show through.
+ *
+ * For an explanation of dither offsets, see the GdkRGB documentation. In brief, the
+ * dither offset is important when scrolling (so you can redraw half an image but keep the
+ * dithering "lined up" between the part you drew first and the part you drew previously).
+ * For unscrolled images, the offset can always be 0.
  **/
 void
 gdk_pixbuf_render_to_drawable (GdkPixbuf *pixbuf,
@@ -247,6 +253,13 @@ gdk_pixbuf_render_to_drawable (GdkPixbuf *pixbuf,
  *
  * Renders a rectangular portion of a pixbuf to a drawable.  This is done using
  * GdkRGB, so the specified drawable must have the GdkRGB visual and colormap.
+ *
+ * This function has a performance penalty; it makes two synchronous
+ * round trips to the X server (creating a bitmask and a GC), and it
+ * draws the contents of the bitmask. If performance is crucial,
+ * consider handling alpha yourself and using
+ * gdk_pixbuf_render_to_drawable(). On the other hand it's more convenient
+ * than gdk_pixbuf_render_to_drawable() because it handles the alpha channel.
  **/
 void
 gdk_pixbuf_render_to_drawable_alpha (GdkPixbuf *pixbuf, GdkDrawable *drawable,